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INTRODUCTION 


OVERVIEW 


"LOOK! It’s a bubblesort!" 

"No!" 

"It’s a mergesort?" 

"Wrong again' It’s SUPERSORT'! 


SUPERSORT is an ultra high-speed sorting routine written in machine language. You 
incorporate it into your BASIC programs according to your needs. It takes up less than 

1000 bytes of memory, yet it can sort a thousand 30-byte names in less than 3.9 seconds 
and a thousand i-byte items in less than one second. SUPERSORT supports records as large 
as 256 bytes, and it can process as many as 10,000 records, depending on your memory size, 


The diskette contains a number of files to meet several needs. You can’t use SUPERSORT 

with DOS I because SUPERSORT uses an autoload feature, However, the diskette contains DOS 
II, The AUTORUN. SYS file on the SUPERSORT diskette is the autoload. Don’t confuse this 
file with ATARI’s normal AUTORUN.SYS, which loads the RS-232C handler. The SUPERSORT 
diskette also includes the assembler editor source code to allow you to modify the 

program to fit you needs. Other files on the diskette are mentioned in the 

Troubleshooting and Advanced Technical Information sections. 


SUPERSORT combines C. Hoare’s QUICKSORT with a standard insertion sort, For a more 
thorough discussion of SUPERSORT and sort routines in general, see Knuth, Donald E,, The 
Art of Computer Programming, Vol. 3, 723 pp., Addison-Wesley, 1973. (Page 114 contains 

a discussion of C. Hoare’s QUICKSORT,) 


REQUIRED ACCESSORIES 


164K RAM 
ATARI 310 Disk Drive 
ATARI BASIC Language Cartridge 


OPTIONAL ACCESSORIES 


ATARI Assembler Editor Cartridge 


PRELIMINARY STEPS 


Using SUPERSORT is easy. First, duplicate AUTORUN.SYS from the SUPERSORT diskette onto 
the diskette containing the BASIC program with data you want to sort. Next, add several 

lines of code to your BASIC program to set up SUPERSORT. (1) You add a calling routine 
specifying several parameters, such as record and number of keys, by which SUPERSORT 

sorts your data. (2) You store in one long string the items you want sorted, (3) 

Optionally, you code an output format for your sorted records, A calling routine appears 

in the Sample Applications section. Lines 1000-1100 set up the parameters to call 
SUPERSORT, 


-~{- 


When you’re ready to run your program, SUPERSORT loads itself into memory as an 
AUTORUN.SYS file when you boot up your diskette. It installs itself below BASIC in 
location $1D0A but remains invisible until your program calls it, To sort your data, run 


your BASIC program as usual. SUPERSORT sorts the entire string in ascending order by your 
specified key. 


GETTING STARTED 


1. Insert the ATARI BASIC Language Cartridge in the (Left Cartridge) slot of your 
computer. 


2. Turn on your disk drive. 


3. When the BUSY light goes out, open the disk drive door and insert the SUPERSORT 
diskette with the label in the lower right-hand corner nearest to you. 


4, Turn on your computer and TV set, 
Ss SUPERSORT will install itself below BASIC in RAM when you boot the DOS. To verify its 
presence, either compare your FRE(O) memory before writing any code (you should be about 


857 bytes short), or PEEK at location 7434, where you should find the number 104, If you 
can’t verify the presence of SUPERSORT, turn off your computer and start again. 
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USING SUPERSORT 


PREPARING YOUR BASIC PROGRAM 


However you code SUPERSORT into your program, your calling routine must include seven 
parameters: (1) record length, (2) number of keys, (3) starting location of the SUPERSORT 
subroutine, (4) starting location of the sort string, (5) starting location of the last 
record in the sort string, (6) starting location of each sort key and (7) ending location 

of each sort key. A brief discussion of each parameter appears below, followed by 
suggestions for incorporating these variables into your calling routine. 


Record length 


This parameter specifies the fixed length of your records. POKE this length into location 
$600 (15:36), (Line 1000 of the sample routine shows one way to code this.) All the 

records must be the same length, and corresponding data fields must be the same length 
across records. Make your data fixed-length by padding data shorter than its field length 
with trailing blanks. A data record is one set of fields to be sorted as a unit. For 
example, a record for a mailing list might comprise fields for a name, address, and zip 
code. Figure 1 shows a schematic of two records, 


enn ee ee Record Lorrrrrr re een nnn Record 2 -------- 


| Field 1 | Field 2 | Field 3 | Field 1 | Field 2 | Field 3 | 
C10) (iS) C10) (10) (45) C10) 
aaa 35 characters----- = ae 35 characters ----- 2 


Figure 1. Sample Dats Records 


Any of these fields can also be the keys by which SUPERSORT sorts your records, (A key is 
the criteria used to sort records.) SUPERSORT can sort on any key, and it can sort on as 
many as S9 keys. In the mailing list example, suppose we want to sort by two keys, first 
by zip code and then by name. We would specify the zip code field as our primary key and 
the name field as our secondary key. SUPERSORT would therefore sort numerically by zip 
code and withinin zip code alphabetically by name. If we set the name field at 10 bytes, 

we would pad any name less than 10 bytes with trailing blanks. (Assuming zip codes are 
all 3 bytes long, padding isn’t necessary in this field.) An example of how to pada 

field is shown in line 710, 


Number of keys 


This parameter specifies the number of keys by which you want to sort your file. POKE 
this value into location $464C (1612), (Line 1010 of the sample routine shows one way to 
code this.) 


¢*+ 4+ ¢ 


Starting and ending locations of each sort key 


You need to POKE the starting and ending character number within the string of each key 
by which you want to sort your data, POKE the starting location of your primary key into 
1613, and the ending location into 1702. POKE the starting location of each additional 
key into 1614, 1615, and so on, and the ending location of each additional key into 1703, 
1704, and so on. Lines 1020-1100 of the sample calling routine contain the POKEs, 
Characters are counted starting with 0 for the first character of a record, to a maximum 
specified by record length, which is POKEd at location 1536-1, 


THE USR CALL 
A call of SUPERSORT consists of three values? 


JUNK = USR(7434,START,LAST) 


_ Starting location of SUPERSORT | 

Code a US5R function containing three values--starting location of SUPERSORT, starting 
location of the sort string, and starting location of the last record in the sort string, 
(Line 1270 of the sample routine shows one way to code this.) The first value, starting 
location of SUPERSORT, calls the program and is always the value 7434, 


Starting location of sort string 


This second value in the USR function tells SUPERSORT where to begin sorting. Use an ADR 
function to specify this value and place this code before the line of code for your USR 
function, (Line 1270 of the sample routine contains the ADR function.) For example, to 

sort string BUF$, the value ADR(BUFS) indicates its starting location. 


Starting location of last record in sort string 


This third value in the USR function lets SUPERSORT determine the end of the sort string, 
Be especially careful in specifying this number. Using the wrong number could cause 
SUPERSORT to continue sorting past your string and rearrange your program code or the 
Operating System RAM! Before using SUPERSORT, check that the starting location of the 
last record in the sort string is a valid value. You can do this by including the 

Following two lines of BASIC code in your program before your USR calli 


X=(LAST-START)/RLENG | 
IF X2>INT(X) THEN FRINT "ERROR IN ADDRESS CALCULATIONS" !?STOF 


The formula to calculate the address of the starting location of the last record in the 
sort string is! 


ADR(BUFS) + LEN(BUF$) - 2#RLENG 


where ADR(BUFS$) is the starting location of your sort string, LEN (BUFS$) is the total 


length of your sort string, and RLENG is your record length. You subtract two RLENGs 


because SUPERSORT requires you to include an empty record at the beginning and at the end 


of your sort string. Place this code before the line of code for your USR function. (Line 
1210 of the sample routine contains the function.) 


INCORPORATING THESE VARIABLES INTO YOUR CALLING ROUTINE 


A calling routine appears in the Sample Applications section and also on the diskette 
(the file name is DEMO.BAS) so that you can try it out, 


Remember to include an empty record at the beginning and the end of your sort string. 
Failure to start your sort string with an empty record causes the first real record to be 
overwritten, and so you’ll lose data. Failure to end your sort string with an empty 
record causes SUPERSORT to overwrite the bytes following your last record-—either you'll 
just lose some data or the whole program could crash, 


FORMATTING YOUR SORT STRING IN YOUR BASIC PROGRAM 


For SUPERSORT to sort your string correctly, you’ll have to format it first, A field must 
be the same length across records. Therefore, all the values for a field will always be 
as long as the longest value for that field. | 


DATA "JOHNSON 121 OAK WAY ANY TOWN" 
DATA "SMITH 1310 MAIN ST. ANYTOWN" 


These strings each contain one record having three fields. JOHNSON and SMITH are the 
first field, padded with trailing blanks te lengthen the data to 10 bytes each. The _ 
second field in each record is padded to lengthen its data to 15 bytes each, and the 
third to 10 bytes each. To sort this string, we would first need to add an empty record 
at the beginning and at the end. 


After SUPERSORT completes its sorting, it stores the results back in the original string, 
Therefore, save your original, unsorted data string somewhere else (in your program or in 
another file, depending on the size of your sort string) if you want to preserve it, 


TROUBLESHOOTING | ~ 


ERROR CODES AND MESSAGES 


Because you create your own calling and formatting program, every BASIC error is 
possible. You'll need to track down these problems yourself, SUPERSORT does no 
error-checking and it contains no special error codes or messages. If you enter bad 
values, you could get one of three results. You might run SUPERSORT but get your data 
back unsorted. Or, with a more severe error, you might get back a jumbled sort, Or, in 

the worst case, the program will crash and you’ll need to turn off your computer. To 

guard against such an event, save your BASIC program before calling SUPERSORT. Then, - 


should something go wrong, simply reload your program and look over your variables before 
rerunning the program. 


PROGRAM OPERATION LIMITATIONS AND WARNINGS 
Using vs not using MEM.SAV 


The SUPERSORT diskette contains the utility MEM.SAV, which prevents your program from 

being destroyed when you call DOS II and prevents SUPERSORT from being lost in RAM. 

However, MEM.SAV slows disk operations since it saves and reloads a portion of RAM each 

time you call DOS IT, and it reserves 45 sectors on the diskette for its own use. You can 

omit this function by deleting the file on your disk (use the DOS II menu selection D to 

‘delete the file), You can reinstate it when you want to by using menu selection N (CREATE 

MEM.SAV),. Remember, though, that whenever you omit MEM.SAV from a diskette, calling DOS = 
will destroy SUPERSORT. If you later run your BASIC program calling SUPERSORT, the system 

will crash and you will have lost your BASIC program as well! 


Pressing SYSTEM RESET or calling DOS 
Pressing the SYSTEM RESET key has no ill effect on SUPERSORT, 


‘If you call DOS and you haven’t included MEM.SAYV on your diskette, then DOS will 


overwrite SUPERSORT in RAM. If MEM.SAV is in effect, it reloads SUPERSORT once DOS has 
reloaded into RAM. 


ADVANCED TECHNICAL INFORMATION 


The following modifications are recommended for advanced hobbyists only. The first 
modification tends to slow down SUPERSORT. 


USING DOUBLE-BYTE RECORDS 


As written, SUPERSORT accepts only single-byte record lengths, even if you move TREC. 
However, you can force SUPERSORT to accept double-byte records since the record length 
(RLENG) is used only during additions. Because the addition is already double-byte (to 
support propagation), you need only change hi byte additions from ADC #0 to ADC RLENGHI, 


SAVING MEMORY SPACE 


SUPERSORT currently has no subroutines because Parameter passing is time-consuming. 
However, if you need more memory, you can reduce the size of the routine as much as 
one-third to one-half by rewriting to include subroutines. You can also eliminate 155 
bytes by removing the insertion sort (labels Q9 - L214), If you choose to eliminate the 

- insertion sort, you must assign label M to one and then reassemble the program. The 
partition size is normally set to 9, 


SAPTIPLE APPLICATIONS 


SAMPLE CALLING ROUTINE 


Below is an example of a calling routine you could include in your BASIC program to set 
up the conditions for using SUPERSORT. This is the listing for the same calling routine 
on the diskette with the file name DEMO.BAS, 


REM 
REM 
REM 


RLE 
FRI 
INF 
REM 
REM 
REM 


SUFERSORT REV 3.0 DEMO FROGRAM 
D. YOCUM, 11/19/81 


THIS FROGRAM ALLOWS THE USER TO DEFINE THE NUMEER . 

OF FIELDS, FIELD SIZE AND NUMBER OF RECORDS FOR SORTING. 
YOU THEN SPECIFY WHICH FIELDS TO SORT BY... 

SUPERSORT DOES THE REST. ALL FIELDS ARE THE 

SAME SIZE IN THIS EXAMFLE, THIS IS NOT 
REQUIRED BY SUFERSORT, HOWEVER. 7 

EKKO OKO KOKO OK KOK OKO XO OK KOK OK OKO OKO KOKO KOK KOK 
MAJOR VARTABLES $ : 

BUF «++ MAIN SORT BUFFER. ALL RECORDS ARE STORED HERE. 
TEMF'S e+e TEMP. INPUT STRING FOR FIELDS 

BLANKS 4... FILLED WITH ELANKS. USED TO FAD FIELDS. 

KEY) +++ HOLDS NUMBERS OF FIELDS TO SORT EY. 

FIELDS ... NUMBER OF FIELDS FER RECORD. 

FLENG +++ NUMBER OF CHARS FER FIELD. 

NREC +++ NUMBER OF RECORDS 

RLENG «++ NUMBER OF CHARACTERS FER RECORD 

NKEYS +++ NUMBER OF SORT KEYS IN ARRAY KEY() 

BUFSIZE «+. TOTAL LENGTH OF BUFS 

KEYSTART.+.+ STARTING LOCATION IN BUFS OF A KEY. 

C +++ POINTER TO START OF NEXT FIELD ON OUTFUT. 

LAST +++ ADDRESS OF START OF LAST RECORD IN BUF. 

2K KORO IKK OK KKK OK KKK KKK KKK KKK KOKO KKK KOK OK KOK KOKO OK KK OK OKOK 


BORO ICICI JO OOK OK OOK OOOO OK OR KOK KOK OKO OKI KKK KOK KOK 
INFUT FIELD NUMBER, SIZE AND RECORD COUNT 
FORO OO OO OK OOK OOK CIO IORI OK OOK OO OKO OK OOK KOK KOK COOK IOK 


NT CHRS$ (125) 3" SUPERSORT REY 3.0 DEMO FROGRAM " 
NT SPRINT 

NT "HOW MANY FIELDS FER RECORD" 

UT FIELDS 

NT "HOW MANY CHARACTERS FER FIELD" 

UT FLENG 

NG=FIELDSXFLENG 

NT "HOW MANY RECORDS TO INFUT"$ 

UT NREC 


ZOO OIC ICIOIORO OOOO ZO IOI IO OK OKO OKO ICO IIOK OK KKK 
COMPUTE SIZE REQUIRED FOR BUFS INCLUDING 2 BLANK RECORDS 


REM DIMENSION STRINGS ACCORDINGLY 

REM OK YK OK OK KKK RK KKK 0K KKK KKK KK KK KKK KOK KKK OK KK KKOK KOKO KOK KOK KOK KOK KK KOK OK KOK 
REM 

EUFSTIZE=(NREC+2) *RLENG 

DIM BUFSCBUFSIZE), TEMPS (FLENG ) BLANKS (FLENG) , KEY (FIELDS) 
REM 

REM BLANKS IS FILLED WITH ELANKS FOR FADDING 

REM 

BUF 6= i eB] 

FOR I=1 TO FLENG? BLANKS (T)=" "SNEXT I 

REM 

REM STICK A BLANK RECORD AT THE BEGINNING OF EBUFS 

REM 

GOSUE 1470 

REM 

FEM KK KKK KOKO KOK KKK KOK KK OKOK KKK KKK 

REM INFUT DATA FOR EACH RECORD 


FREM (KK KKK KKK KKK KOKO OK KKK KKK KKK KK 


REM 

FOR RECNT=1 TO NREC 
FRINT 

FOR FCNT=1 TO FIELDS 


FRINT “INFUT RECORD "$RECNT$" FIELD "$FCNT 

INFUT TEMPS | 

BUF S$ (LEN(BUFS$)4+1)=TEMPS 

REM | 

REM FAD WITH BLANKS IF THIS FIELD IS TOO SHORT 

REM 

IF LEN( TEMPS) <FLENG THEN BUFS(LEN(BUFS$)+1)=BLANK$(1,FLENG-LEN(TEMF$)) 
NEXT FCNT 


NEXT RECNT 

REM 

REM STICK A BLANK RECORD AT THE END OF BUFS 
REM 

GOSUE 1470 

REM 


REM GOO OOOO OOK OOOO OO OKO OOK OOK OK IO KK KOK KOK KKK 
REM INFUT THE FRECEDENCE OF THE FIELDS FOR SORTING 
REM OEE EEE EEA EN REL E SER EEREAS RARER ERE SE A RARER 


REM 


FRINT tFPRINT | 

FRINT "SORT BY WHICH FIELD (1-"$FIELDS;")"? 
FOR NKEYS=1 TO FIELDS 

INFUT X 

IF X=0 THEN FOF {GOTO 930 

KEY (NKEYS ) =X 

TF NKEYS=FIELDS THEN 920 

?P SPRINT "IF THOSE FIELDS MATCH, WHICH SHOULD" 
FRINT "IT SORT BY NEXT (0 WHEN DONE)D'? 

NEXT NKEYS 

REM NKEYS NOW HAS NUMBER OF KEYS 
NKEYS=NKEYS-1 


1430 
1440 


1460 


REM 

REM KKK KKK KKK KOKORO KOKOK KOK KKK OKOK 
REM SET UF SUPERSORT 

REM KKK 0K KKK KKK OKOKOKOKOK KOKO KOK 
REM 

FOKE 1536,RLENG?REM RECORD LENGTH 


FOKE 1612,NKEYS!REM NUMBER OF KEYS 

FOR KCNT=1 TO NKEYS 

REM 

REM COMPUTE BEGINNING CHAR # OF KEY FIELD 
REM 


KEYSTART=CKEY CKCNT )-1) XFLENG 

FOKE 1612+KCNT,KEYSTARTSREM STARTING CHAR FOR KEY 
REM FOKE ENDING CHAR# OF KEY 

POKE 1701+KCNT,KEYSTART+FLENGS REM SENG CHAR FOR KEY 
NEXT KCNT 

REM KAKA KKK KAKA KK AK KAKA AK KKK KKK NK 

REM DISPLAY UNSORTED RECORDS 

REM OKO OKO KOKKKK OK 

PRINT ¢ PRINT 

FRINT "UNSORTED RECORDS" 

GOSUE 1520$REM FRINT FORMATTER 

REM 

REM COMFUTE STARTING ADDRESS OF LAST RECORD IN BUFS 


REM THIS SHOULD IMMEDIATELY FPRECEED THE USR CALL. | 

REM 

LAST=ADR (CBUFS$)+LENCBUFS )-2xXRLENG : 
REM 


NAVE SOS SS SCCCS OOS SE SES OSE OS 3 
REM CALL SUPERSORT! 

REM KOKOKXOKOKKKKOKOKKOKOKOOKOKOK KOK OK OK 
REM 

JUNK=USRK (7434,ADR (CBUFS),LAST) 
REM 

REM OOOO OK KK OOK KK KKK KK 
REM DISPLAY SORTED RECORDS 
REM KKK KKKKKKKOK KKK OK KOK KK 


REM 

FRINT sFRINT tFPRINT "SORTED RECORDS" 
GOSUE LS202REM FRINT FORMATTER 

END 

REM 


REM OK OOOICO OOK OK OO OK OK OK OKO KOK NOK NOK KOK OK 
REM SUBROUTINES 
REM OOK OKO OOOOK SOK OKO OK OK KKK KK OK KOK 


REM THIS SUBROUTINE CREATES A BLANK RECORD 
REM IN THE SORT BUFFER. IT IS USED TO MAKE 
REM EOTH THE FIRST AND LAST BLANK RECORDS 
REM REQUIRED BEY SUFERSORT. 

REM YK FR CCC KC OK BC OK 3K 3K KK OK KOK 9K KOK KK KK OK KK KOK OK OK KOK KO 


-~10- 


1470 
1480 
1490 
1500 
1510 
1520 
1530 
1540 
1350 
1540 
1570 
1580 
1590 
1600 
1610 
1620 
1630 
1640 


FOR IT=1 TO FIELDS 

BUF S CLENCEUPF $)+1>=BLANKS 

NEXT I 

RETURN 

REM 

REM 2000000000 OOO OOOO KK KK 
REM OUTFUT DISPLAY FORMATTER 

REM OOOO OOK OOOO OK KOK OKO KKK KOK XOKOK 
REM 

C=FLENGXFIELDS+13REM SKIF FIRST BLANK oe 
FOR I=1 TO NREC 

PRINT 

FOR J=1 TO FIELDS 

FRINT BUF S(C,C+FPLENG-1), 

C=C+FLENG 

NEXT J 

NEXT TI 

RETURN 


~Li- 
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Limited Warranty on Media and Hardware Accessories. We, Atari, Inc., guarantee to you, the original 
retail purchaser, that the medium on which the APX program is recorded and any hardware 
accessories sold by APX are free from defects for thirty days from the date of purchase. Any applicable 
implied warranties, including warranties of merchantability and fitness for a particular purpose, are 
also limited to thirty days from the date of purchase. Some states don't allow limitations on a warranty’s 
period, so this limitation might not apply to you. If you discover such a defect within the thirty-day 
period, call APX for a Return Authorization Number, and then return the product along with proof of 
purchase date to APX. We will repair or replace the product at our option. 


You void this warranty if the APX product: (1) has been misused or shows signs of excessive wear, 
(2) has been damaged by use with non-ATARI Home Computer products; or (3) has been serviced or 
modified by anyone other than an Authorized ATARI Computer Service Center. Incidental and conse- 
quential damages are not covered by this warranty or by any implied warranty. Some states don't allow 
exclusion of incidental or consequential damages, so this exclusion might not apply to you. 


Disclaimer of Warranty and Liability on Computer Programs. Most APX programs have been written 
by people not employed by Atari, Inc. The programs we select for APX offer something of value that we 
want to make available to ATARI Home Computer owners. To offer these programs to the widest 
number of people economically, we don’t put APX products through rigorous testing. Therefore, APX 
products are sold “as is,” and we do not guarantee them in any way. In particular, we make no warranty, 
express or implied, including warranties of merchantability and fitness for a particular purpose. We are 
not liable for any losses or damages of any kind that result from use of an APX product. 


For the complete list of current 
APX programs, ask your ATARI retailer 
for the APX Product Catalog 


ay 


\ ¥ fae 
PROGRAM 
EXCHANGE 

P.O. Box 3705 

santa Clara, CA 95055 


We re interested in your experiences with APX programs 
and documentation, both favorable and unfavorable. 
Many of our authors are eager to improve their programs 
if they know what you want. And. of course. we want to 
know about any bugs that slipped by us, so that the 
author can fix them. We also want to know whether our 


1. Name and APX number of program. 


Review Form 


instructions are meeting your needs. You are our best 
source for suggesting improvements! Please help us by 
taking a moment to fill in this review sheet. Fold the sheet 
in thirds and seal it so that the address on the bottom of 
the back becomes the envelope front. Thank you for 
helping us! 


2. If you have problems using the program, please describe them here. 


3. What do you especially like about this program? 


4. What do you think the program's weaknesses are”? 


5. How can the catalog description be more accurate or comprehensive? 


6. Onascale of 1 to 10. 1 being “poor” and 10 being “excellent”. please rate the following aspects of this program: 


Easy to use 


User-oriented (e.g., menus. prompts. clear language) 


Enjoyable 

Self-instructive 

Useful (non-game programs) 
Imaginative graphics and sound ~ 


7. Describe any technical errors you found in the user instructions (please give page numbers). 


ree sehen nneseerssnsayresnesepeneninenenteereremsnmneneee 
a TS eS SSeS SiS SS SSS SSS SSS Shs SSS Sa sh sess sss UES 


8. What did you especially like about the user instructions? 


ET a TT EO Fa ESS TS SS TE OSS AT PR SG RISE OS 
<< mE AE SSS So PEER RS SS ST STP SE SSS SES a GEG RE StS EES 


9. What revisions or additions would improve these instructions? 
i ae 
PSS SSS SSS SSS SSS SSS SSS TSS Ss SS Ss sss ea tresses 
Re a Ee Ie ea re 


10. On a scale of 1 to 10, 1 representing “poor” and 10 representing “excellent”, how wouid you rate the user 
instructions and why? 


11. Other comments about the program or user instructions: 


From 


STAMP 


ATARI Program Exchange 
P.O. Box 3705 
Santa Clara. CA 95055 


[seal nere} 


